Improve GtkStack documentation

As has been pointed out in
https://bugzilla.gnome.org/show_bug.cgi?id=725711
it is a little confusing that we have the concept of
a visible child and of the child being visible itself.

diff --git a/gtk/gtkstack.c b/gtk/gtkstack.c
index 6d3a57a407cb85388bf878b123c31a98995b276a..3b338be7a2eb4b9bb47b9dd6a08e00c29295731e 100644 (file)
--- a/gtk/gtkstack.c
+++ b/gtk/gtkstack.c
@@ -1392,6 +1392,10 @@ gtk_stack_get_visible_child_name (GtkStack *stack)
  * two will be animated with the current
  * transition type of @stack.
  *
+ * Note that the @child widget has to be visible itself
+ * (see gtk_widget_show()) in order to become the visible
+ * child of @stack.
+ *
  * Since: 3.10
  */
 void
@@ -1430,6 +1434,10 @@ gtk_stack_set_visible_child (GtkStack  *stack,
  * two will be animated with the current
  * transition type of @stack.
  *
+ * Note that the child widget has to be visible itself
+ * (see gtk_widget_show()) in order to become the visible
+ * child of @stack.
+ *
  * Since: 3.10
  */
 void
@@ -1449,6 +1457,10 @@ gtk_stack_set_visible_child_name (GtkStack   *stack,
  *
  * Makes the child with the given name visible.
  *
+ * Note that the child widget has to be visible itself
+ * (see gtk_widget_show()) in order to become the visible
+ * child of @stack.
+ *
  * Since: 3.10
  */
 void